home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu017.dms / pu017.adf / Graphics / Graphics.doc < prev    next >
Text File  |  1990-01-30  |  26KB  |  861 lines
  1. 3    GRAPHICS
  2.  
  3. 3.1  INTRODUCTION
  4.  
  5. We have now looked at how to open different types of screens,
  6. and how to open different types of windows connected to the
  7. screens etc. It is all very good, but what would Intuition be
  8. without any graphics to display in the screens/windows?
  9.  
  10. Intuition's main idea is to make the communication between
  11. the program and the user as easy as possible. Graphics enables
  12. you to display the results that the computer has calculated in
  13. an understandable way (a picture says more than...). Graphics
  14. makes it also much easier to use the program, and can warn the
  15. user if something dangerous is going to happen: It is very easy
  16. to press the wrong button if you have got a question like "OK
  17. to erase disk?", but if there also had been a picture
  18. showing a cross with the text "RIP" on, you would probably
  19. have been a bit more careful.
  20.  
  21. There exist both a low- and a high-level way of making
  22. graphics. The low-level approach (Graphics Primitives) is
  23. not described in this chapter since it is not related to
  24. Intuition. The low-level graphics routines are very fast, but
  25. if you are not careful they can trash menus etc. We will here
  26. concentrate our self on the high-level approach which is
  27. supported by Intuition, and is a safe way of drawing.
  28.  
  29.  
  30.  
  31. 3.2  LINES TEXT PICTURES
  32.  
  33. Intuition gives you three different methods of making graphics:
  34. - You can draw lines (Borders).
  35. - Print text (IntuiText).
  36. - Or you can directly print graphics images (Images).
  37.  
  38.  
  39.  
  40. 3.3  BORDERS
  41.  
  42. Border has a bit misleading name since you are not limited to
  43. only draw borders, you may draw any kind of shapes which is
  44. made out of connecting lines. A Border structure may also be
  45. connected to other Border structures, so everything which can
  46. be drawn with lines, can be drawn with Intuition's Border
  47. structure.
  48.  
  49.  
  50.  
  51. 3.3.1  THE BORDER STRUCTURE
  52.  
  53. When you want to draw lines you need to declare and initialize
  54. a Border structure which look like this:
  55.  
  56. struct Border
  57. {
  58.   SHORT LeftEdge, TopEdge;
  59.   SHORT FrontPen, BackPen, DrawMode;
  60.   SHORT Count;
  61.   SHORT *XY;
  62.   struct Border *NextBorder;
  63. };
  64.  
  65. LeftEdge, TopEdge: Start position of the lines.
  66.  
  67. FrontPen:          Colour register used to draw the lines.
  68.  
  69. BackPen:           This variable is for the moment unused.
  70.  
  71. DrawMode:          Must be either JAM1 or XOR. If the JAM1 flag
  72.                    is set, the colour specified (FrontPen) will
  73.                    be used to draw the lines regardless what
  74.                    the background colour is. The XOR flag makes
  75.                    the lines to be drawn with the binary 
  76.                    complement of the background colours.
  77.  
  78. Count:             The number of coordinates there is in the XY
  79.                    array. (See below for more information.)
  80.  
  81. XY:                A pointer to an array of coordinates used to
  82.                    draw the lines. (See below for more
  83.                    information.)
  84.  
  85. NextBorder:        A pointer to the next Border structure if
  86.                    there exist one, else NULL.
  87.  
  88.  
  89.  
  90. 3.3.2  COORDINATES
  91.  
  92. If you want to draw this:
  93.  
  94. (10,10)        (25,10)
  95.    *--------------*
  96.                   |      (35,12)
  97.                   |         *
  98.                   |         |
  99.                   *---------*
  100.                (25,14)   (35,14)
  101.  
  102. The array of coordinates would look like this:
  103.  
  104. SHORT my_points[]=
  105. {
  106.   10,10, /* Start at position (10,10) */
  107.   25,10, /* Draw a line to the right to position (25,10) */
  108.   25,14, /* Draw a line down to position (25,14) */
  109.   35,14, /* Draw a line to the right to position (35,14) */
  110.   35,12  /* Finish of by drawing a line up to position (35,12) */ 
  111. };
  112.  
  113. The array contains 5 pair of coordinates, so the variable Count
  114. should be set accordingly. The entire Border structure would
  115. therefore look something like this:
  116.  
  117. struct Border my_border=
  118. {
  119.   0, 0,        /* LeftEdge, TopEdge. */
  120.   3,           /* FrontPen, colour register 3. */
  121.   0,           /* BackPen, for the moment unused. */
  122.   JAM1,        /* DrawMode, draw the lines with colour 3. */
  123.   5,           /* Count, 5 pair of coordinates in the array. */
  124.   my_points,   /* XY, pointer to the array with the */
  125.                /* coordinates. */
  126.                /* (Remember my_points == &my_points[0]) */
  127.   NULL         /* NextBorder, no other Border structures */
  128.                /* comes after this one. */
  129. };
  130.  
  131.  
  132.  
  133. 3.4  HOW TO USE THE BORDER STRUCTURE
  134.  
  135. The Border structure is either used to draw lines in a screen
  136. or window, but can also be used to draw lines connected to a
  137. Gadget, Requester or Menu. (See chapter 4, 5 and 7 for more
  138. information about Gadgets, Requesters and Menus.)
  139.  
  140. If you want to connect a Border structure with a Gadget etc,
  141. you simply initialize the Gadget structure with a pointer to
  142. the Border structure, and Intuition will draw the lines for
  143. you. This will be explained later.
  144.  
  145. If you want to draw the lines in a screen or window you need to
  146. tell Intuition that you want it to use the structure to make
  147. some lines. You do it by calling the function DrawBorder():
  148.  
  149. Synopsis:  DrawBorder( rast_port, border, x, y );
  150.  
  151. rast_port: (struct RastPort *) Pointer to a RastPort.
  152.  
  153.            If the lines should be drawn in a window, and
  154.            my_window is a pointer to that window, you write:
  155.            my_window->RPort.
  156.           
  157.            If the lines should be drawn in a Screen, and
  158.            my_screen is a pointer to that screen, you write:
  159.            my_screen->RastPort.
  160.  
  161. border:    (struct Border *) Pointer to a Border structure
  162.            which has been initialized with your requirements.
  163.  
  164. x:         (long) Number of pixels added to the x coordinates.
  165.  
  166. y:         (long) Number of lines added to the y coordinates.
  167.  
  168.  
  169. A call to draw some lines using my_border structure would look
  170. something like this:
  171.   
  172.   DrawBorder( my_window->RPort, &my_border, 0, 0 );
  173.  
  174. If you have created a Border structure which, for example,
  175. draws a box, you can draw several boxes at different places
  176. just by changing the LeftEdge, RightEdge fields of the Border
  177. structure, or by changing the x, y fields in the function call.
  178. This shows how versatile Intuition's high-level way of drawing
  179. is.
  180.  
  181.  
  182.  
  183. 3.4  TEXT
  184.  
  185. Printing text in the Display is supported by the IntuiText
  186. structure. It is quite similar to the Border structure, and is
  187. executed in the same way. The only difference is that you need
  188. to tell Intuition what Font you want to use, and what text to
  189. print.
  190.  
  191.  
  192.  
  193. 3.4.1  THE INTUITEXT STRUCTURE
  194.  
  195. When you want to print text you need to declare and initialize
  196. a IntuiText structure which look like this:
  197.  
  198. struct IntuiText
  199. {
  200.   UBYTE FrontPen, BackPen;
  201.   UBYTE DrawMode;
  202.   SHORT LeftEdge;
  203.   SHORT TopEdge;
  204.   struct TextAttr *ITextFont;
  205.   UBYTE *IText;
  206.   struct IntuiText *NextText;
  207. };
  208.  
  209. FrontPen:          Colour register used to draw the text with.
  210.  
  211. BackPen:           Colour register used to draw the background
  212.                    of the text.
  213.  
  214. DrawMode:          There exist three different way of printing
  215.                    the text:
  216.  
  217.                    JAM1  The colour specified (FrontPen) will
  218.                          be used to draw the text with, the
  219.                          background is unchanged.
  220.  
  221.                    JAM2  The FrontPen colour will be used to
  222.                          draw the text with, the background is
  223.                          drawn with the BackPen colour.
  224.  
  225.                    XOR   The text is drawn with the the binary
  226.                          complement of the background.
  227.  
  228. LeftEdge, TopEdge: Start position of the text.
  229.  
  230. ITextFont:         A pointer to a TextAttr structure which
  231.                    tells Intuition what font, size and style
  232.                    etc to print the text with. Set to NULL if
  233.                    you want to use the default font. (See below
  234.                    for more information.)
  235.  
  236. IText:             A pointer to a NULL-terminated string that
  237.                    should be printed.
  238.  
  239. NextText:          A pointer to the next IntuiText structure if
  240.                    there exist one, else write NULL.
  241.  
  242.  
  243.  
  244. 3.4.2  FONTS
  245.  
  246. You can tell Intuition to print the text with a specific font/
  247. style. You only need to declare and initialize a TextAttr
  248. structure, and give your IntuiText structure a pointer to the
  249. TextAttr structure.
  250.  
  251. The TextAttr structure look like this:
  252.  
  253. struct TextAttr
  254. {
  255.   STRPTR ta_Name;
  256.   UWORD ta_YSize;
  257.   UBYTE ta_Style
  258.   UBYTE ta_Flags;
  259. };
  260.  
  261.  
  262. We will for the moment only discuss how to access the ROM-fonts
  263. (the fonts which are always available in ROM), and will wait
  264. with Disk-fonts (fonts which your program can access from the
  265. disk).
  266.  
  267. There exist only one ROM-font for the moment, and that one is
  268. called Topaz. It exist in two sizes, 64/32 and 80/40 (high-/
  269. low-resolution) characters per line, and can be printed in five
  270. different styles, normal, bold, italic, underlined and extended,
  271. which can be combined as desired.
  272.  
  273. ta_Name:   Name of the font. Set it to "topaz.font" for the
  274.            moment.
  275.  
  276. ta_YSize:  Font height. Can either be TOPAZ_SIXTY (64/32) or
  277.            TOPAZ_EIGHTY (80/40).
  278.  
  279. ta_Style:  Style (normal, bold, underlined, italic and
  280.            extended). Set the desired flags:
  281.  
  282.              FS_NORMAL      No special style.
  283.              FSF_EXTENDED   Extended font, wider than normal.
  284.              FSF_ITALIC     Italic, slanted 1:2 to the right.
  285.              FSF_BOLD       Bold, thicker than normal.
  286.              FSF_UNDERLINED Underlined, line under the baseline.
  287.  
  288. ta_Flags:  Preferences. Should for the moment be set to
  289.            FPF_ROMFONT.
  290.  
  291.  
  292. Here is an example on how you can print some text with
  293. underlined, italic characters:
  294.  
  295. struct TextAttr my_font=
  296. {
  297.   "topaz.font",                 /* Topaz font. */
  298.   TOPAZ_EIGHTY,                 /* 80/40 characters. */
  299.   FSF_ITALIC | FSF_UNDERLINED,  /* Underlined italic chars. */ 
  300.   FPF_ROMFONT                   /* Exist in ROM. */
  301. };
  302.  
  303. UBYTE my_text[]="This is the text that will be printed!";
  304.  
  305. struct IntuiText my_intui_text=
  306. {
  307.   2,         /* FrontPen, colour register 2. */
  308.   3,         /* BackPen, colour register 3. */
  309.   JAM2,      /* DrawMode, draw the characters with colour 2, */
  310.              /* on a colour 3 background. */ 
  311.   0, 0,      /* LeftEdge, TopEdge. */
  312.   &my_font,  /* ITextFont, use my_font. */
  313.   my_text,   /* IText, the text that will be printed. */
  314.              /* (Remember my_text = &my_text[0].) */
  315.   NULL       /* NextText, no other IntuiText structures are */
  316.              /* connected. */
  317. };
  318.  
  319.  
  320.  
  321. 3.4.3  HOW TO USE THE INTUITEXT STRUCTURE
  322.  
  323. The IntuiText structure is either used to print text in a
  324. screen or window, but can also be used to print text connected
  325. to a Gadget, Menu or Requester. Same as with drawing lines with
  326. the Border structure.
  327.  
  328. When you want to print text in a window/screen you simply call
  329. the function PrintIText():
  330.  
  331. Synopsis:   PrintIText( rast_port, intui_text, x, y );
  332.  
  333. rast_port:  (struct RastPort *) Pointer to a RastPort.
  334.  
  335.             If the text should be printed in a window, and
  336.             my_window is a pointer to that window, you write:
  337.             my_window->RPort.
  338.           
  339.             If the text should be printed in a Screen, and
  340.             my_screen is a pointer to that screen, you write:
  341.             my_screen->RastPort.
  342.  
  343. intui_text: (struct IntuiText *) Pointer to a IntuiText
  344.             structure which has been initialized with your
  345.             requirements.
  346.  
  347. x:          (long) Number of pixels added to the x position of
  348.             the characters.
  349.  
  350. y:          (long) Number of lines added to the y position of
  351.             the characters.
  352.  
  353.  
  354. A call to print some text using my_intui_text structure would
  355. look something like this:
  356.   
  357.   PrintIText( my_window->RPort, &my_intui_text, 0, 0 );
  358.  
  359.  
  360.  
  361. 3.5  IMAGES
  362.  
  363. We have now looked at how to draw lines and print text. We will
  364. finish off by looking at how to print a whole image directly.
  365. The procedure can be devided into three steps:
  366.  
  367.   1. Declare and initialize the data which should be drawn.
  368.   2. Declare and initialize an Image structure.
  369.   3. Call the function DrawImage() to draw the image.
  370.  
  371.  
  372.  
  373. 3.5.1  IMAGE DATA
  374.  
  375. Intuition wants to have the image data structured into blocks
  376. of 16-bit memory words (UWORD), organized into rectangular
  377. areas (BitPlanes). You may have up to 6 BitPlanes (4 if you are
  378. displaying the image on a high-resolution screen). The colour
  379. of each pixel is determined by the binary number of the
  380. BitPlanes. For example, to get a pixel with colour 6 on a
  381. screen with a Depth of 4, BitPlane zero and three should be 0,
  382. and BitPlane one and two should be 1, since the binary number
  383. 0110 is equal to the decimal number 6.
  384.  
  385. A little arrow can for example look like this:
  386. (1 BitPlane = 2 colours)
  387.  
  388. Image      16-Bit memory words    Hexadecimal representation
  389. ------------------------------------------------------------
  390.  
  391. 0001000    0001 0000 0000 0000    1 0 0 0
  392. 0011100    0011 1000 0000 0000    3 8 0 0
  393. 0111110    0111 1100 0000 0000    7 C 0 0
  394. 1111111    1111 1110 0000 0000    F E 0 0
  395. 0001000    0001 0000 0000 0000    1 0 0 0
  396. 0001000    0001 0000 0000 0000    1 0 0 0
  397. 0001000    0001 0000 0000 0000    1 0 0 0
  398. 0001000    0001 0000 0000 0000    1 0 0 0
  399.  
  400. Even if the Image only is 7 pixels wide, we needed to make the
  401. Image data 16 (bits) pixels wide, since Intuition wants the
  402. data ordered into 16-bit memory words. (Of course, when we
  403. print it out we can tell Intuition that the image should be
  404. only 7 pixels wide.)
  405.  
  406. Each group of four pixels is then translated into a hexadecimal
  407. value. See table:
  408.  
  409.   Binary => Hexadecimal
  410.   ---------------------
  411.   0000 =    0
  412.   0001 =    1
  413.   0010 =    2
  414.   0011 =    3
  415.   0100 =    4
  416.   0101 =    5
  417.   0110 =    6
  418.   0111 =    7
  419.   1000 =    8
  420.   1001 =    9
  421.   1010 =    A
  422.   1011 =    B
  423.   1100 =    C
  424.   1101 =    D
  425.   1110 =    E
  426.   1111 =    F
  427.  
  428. A declaration and initialization of the data for the arrow
  429. image will therefore look like this:
  430.  
  431. UWORD chip my_image_data[]=
  432. {
  433.   0x1000, /* BitPlane ZERO */
  434.   0x3800,
  435.   0x7C00,
  436.   0xFE00,
  437.   0x1000,
  438.   0x1000,
  439.   0x1000,
  440.   0x1000
  441. };
  442.  
  443. Since the image data is made out of one BitPlane, the arrow
  444. will be drawn in colour 1, and the background in colour 0. 
  445.  
  446.  
  447. If the image is wider than 16 pixels you need more than one
  448. word per line. Here is an image which is 20 pixels wide, and
  449. will therefore require two words per line:
  450.  
  451. Image                  16-Bit memory words (2 words)
  452. ---------------------------------------------------------------
  453.  
  454. 11111111111111111111   1111 1111 1111 1111  1111 0000 0000 0000
  455. 00111110000001111100   0011 1110 0000 0111  1100 0000 0000 0000
  456. 00001111100111110000   0000 1111 1001 1111  0000 0000 0000 0000
  457. 00111110000001111100   0011 1110 0000 0111  1100 0000 0000 0000
  458. 11111111111111111111   1111 1111 1111 1111  1111 0000 0000 0000
  459.  
  460.  
  461. We translate the binary numbers into hexadecimal, and we end
  462. up with:
  463.  
  464. UWORD chip my_image_data[]=
  465. {
  466.   0xFFFF, 0xF000, /* BitPlane ZERO */
  467.   0x3E07, 0xC000,
  468.   0x0F9F, 0x0000,
  469.   0x3E07, 0xC000,
  470.   0xFFFF, 0xF000
  471. };
  472.  
  473.  
  474. If we want more than two colours we need more than one
  475. BitPlane. A four-colour face can look something like this:
  476.  
  477. 003333300000     0: Blue (Normal Workbench colours)
  478. 033333330000     1: White
  479. 332232233000     2: Black
  480. 323333323000     3: Orange
  481. 331131133000
  482. 331131133000
  483. 331232133000
  484. 331232133000
  485. 333333333000
  486. 332333233000
  487. 033222330000
  488. 033333330000
  489. 003333300000
  490.  
  491. We translate it into 16-Bit memory words organized into two
  492. Bitplanes (Two BitPlanes = 4 colours):
  493.  
  494. Colour   Bitplane ONE   Bitplane ZERO   SINCE
  495. ------------------------------------------------------
  496. 0        0              0               00 (b) = 0 (d)
  497. 1        0              1               01 (b) = 1 (d)
  498. 2        1              0               10 (b) = 2 (d)
  499. 3        1              1               11 (b) = 3 (d)
  500.  
  501.  
  502. Bitplane ONE          Bitplane ZERO
  503. -----------------------------------------
  504.  
  505. 0011 1110 0000 0000   0011 1110 0000 0000
  506. 0111 1111 0000 0000   0111 1111 0000 0000
  507. 1111 1111 1000 0000   1100 1001 1000 0000
  508. 1111 1111 1000 0000   1011 1110 1000 0000
  509. 1100 1001 1000 0000   1111 1111 1000 0000
  510. 1100 1001 1000 0000   1111 1111 1000 0000
  511. 1101 1101 1000 0000   1110 1011 1000 0000
  512. 1101 1101 1000 0000   1110 1011 1000 0000
  513. 1111 1111 1000 0000   1111 1111 1000 0000
  514. 1111 1111 1000 0000   1101 1101 1000 0000
  515. 0111 1111 0000 0000   0110 0011 0000 0000
  516. 0111 1111 0000 0000   0111 1111 0000 0000
  517. 0011 1110 0000 0000   0011 1110 0000 0000
  518.  
  519.  
  520. Each group of four pixels is then translated into a hexadecimal
  521. value:
  522.  
  523. Bitplane ONE          Bitplane ZERO
  524. -----------------------------------
  525.  
  526. 3 E 0 0               3 E 0 0
  527. 7 F 0 0               7 F 0 0
  528. F F 8 0               C 9 8 0
  529. F F 8 0               B E 8 0
  530. C 9 8 0               F F 8 0
  531. C 9 8 0               F F 8 0
  532. D D 8 0               E B 8 0
  533. D D 8 0               E B 8 0
  534. F F 8 0               F F 8 0
  535. F F 8 0               D D 8 0
  536. 7 F 0 0               6 3 0 0
  537. 7 F 0 0               7 F 0 0
  538. 3 E 0 0               3 E 0 0
  539.  
  540.  
  541. A declaration and initialization of the data for the face image
  542. will therefore look like this:
  543.  
  544. USHORT chip my_image_data[]=
  545. {
  546.   0x3E00, /* Bitplane ZERO */
  547.   0x7F00,
  548.   0xC980,
  549.   0xBE80,
  550.   0xFF80,
  551.   0xFF80,
  552.   0xEB80,
  553.   0xEB80,
  554.   0xFF80,
  555.   0xDD80,
  556.   0x6300,
  557.   0x7F00,
  558.   0x3E00,
  559.  
  560.   0x3E00, /* Bitplane ONE */
  561.   0x7F00,
  562.   0xFF80,
  563.   0xFF80,
  564.   0xC980,
  565.   0xC980,
  566.   0xDD80,
  567.   0xDD80,
  568.   0xFF80,
  569.   0xFF80,
  570.   0x7F00,
  571.   0x7F00,
  572.   0x3E00
  573. };
  574.  
  575. Remember that all Image Data MUST be in Chip Memory!
  576.  
  577.  
  578.  
  579. 3.5.2  THE IMAGE STRUCTURE
  580.  
  581. The Image structure look like this:
  582.  
  583. struct Image
  584. {
  585.   SHORT LeftEdge, TopEdge;
  586.   SHORT Width, Height, Depth;
  587.   SHORT *ImageData;
  588.   UBYTE PlanePick, PlaneOnOff;
  589.   struct Image *NextImage;
  590. };
  591.  
  592. LeftEdge:          X position of the Image.
  593.  
  594. TopEdge:           Y position of the Image.
  595.  
  596. Width:             The actual width of the Image.
  597.  
  598. Height:            The height of the Image.
  599.  
  600. Depth:             Number of Bitplanes used for the Image.
  601.  
  602. ImageData:         A pointer to the Image data.
  603.  
  604. PlanePick:         Which Bitplanes of the displaying element
  605.                    should be changed/affected by the Image.
  606.                    (See below for more information.)
  607.  
  608. PlaneOnOff:        What should happen to the Bitplanes of the
  609.                    displaying element that were not affected.
  610.                    Should they be filled with 1's or 0's. (See
  611.                    below for more information.)
  612.  
  613. NextImage:         A pointer to the next Image structure if
  614.                    there exist one, else NULL.
  615.  
  616.  
  617.  
  618. 3.5.3  PLANEPICK
  619.  
  620. The advantages with the PlanePick/PlaneOnOff fields are that
  621. you can print the Image into a display of any depth, print the
  622. same Image in different colours, and it will eliminate
  623. unnecessary memory-waste when using coloured Images.
  624.  
  625. PlanePick tells Intuition which Bitplanes of the display to be
  626. affected by the Image. For every "picked" plane, the next
  627. successive Bitplane of the image is printed there. For example:
  628.  
  629. If we set PlanePick to 1, Bitplane zero would be affected. If
  630. we then printed the arrow Image, we would get the arrow drawn
  631. with colour 1, and the background drawn with colour 0.
  632.  
  633. If we had instead set PlanePick to 2, Bitplane one would have
  634. been affected, which would result in that the arrow would have
  635. been drawn with colour 2, and the background still drawn with
  636. colour 0.
  637.  
  638.  
  639. If our Image would consist of several Bitplanes, the lowest
  640. picked plane would be affected by the lowest Bitplane, and so
  641. on. If we take our face Image for example, and we want to draw
  642. it with colour 3, 2 1 and 0, we want to affect Bitplane zero
  643. and BitPlane one of the display. We would therefore need to set
  644. PlanePick to 3, see table:
  645.  
  646. Bitplane to affect   PlanePick
  647. ------------------------------
  648.  
  649. No planes affected   0000 = 0
  650. Plane 0              0001 = 1
  651. Plane 1              0010 = 2
  652. Plane 1 and 0        0011 = 3
  653. Plane 2              0100 = 4
  654. Plane 2 and 0        0101 = 5
  655. Plane 2 and 1        0110 = 6
  656. Plane 2, 1 and 0     0111 = 7
  657. Plane 3              1000 = 8
  658. Plane 3 and 0        1001 = 9
  659. Plane 3 and 1        1010 = A
  660. and so on...
  661.  
  662.  
  663. If we want to draw it with colour 5, 4, 1 and 0, we want to
  664. affect Bitplane two and zero:
  665.  
  666. (000=colour 0, 001=colour 1, 100=colour 4, 101=colour 5)
  667.  ^ ^           ^ ^           ^ ^           ^ ^
  668.  210           210           210           210 (BitPlanes)
  669.  
  670. We would then set PlanePick to 5 (0101).
  671.  
  672.  
  673.  
  674. 3.5.4  PLANEONOFF
  675.  
  676. PlaneOnOff decides what should happen to the Bitplanes of the
  677. displaying element that were not affected by PlanePick. Should
  678. these Bitplanes be filled with 1's or 0's.
  679.  
  680. For example, if we want to print the little arrow in colour 5
  681. and the background in colour 1 the pixels should have the
  682. values 0001 (colour 1) and 0101 (colour 5). We want the Image
  683. to affect Bitplane two, so PlanePick is set to 4 (0100). But we
  684. also want Bitplane zero to be filled with 1's, so PlaneOnOff is
  685. set to 1 (0001).
  686.  
  687. With help of PlanePick and PlaneOnOff you can even print filled
  688. rectangles without any Image data. You only need to set Width
  689. and Height as desired, and then set Depth to 0 (no Bitplanes),
  690. PlanePick to 0000 (no Bitplanes should be used) and PlaneOnOff
  691. to the colour you want.
  692.  
  693.  
  694.  
  695. 3.5.5  HOW TO USE THE IMAGE STRUCTURE
  696.  
  697. The Image structure is either used to print images in a screen
  698. or window, but can also be used to print images connected to a
  699. Gadget, Menu or Requester. Same as Intuition's other Graphics
  700. structures.
  701.  
  702. When you want to print an image in a window/screen you simply
  703. call the function DrawImage():
  704.  
  705. Synopsis:  DrawImage( rast_port, image, x, y );
  706.  
  707. rast_port: (struct RastPort *) Pointer to a RastPort.
  708.  
  709.            If the images should be drawn in a window, and
  710.            my_window is a pointer to that window, you write:
  711.            my_window->RPort.
  712.  
  713.            If the images should be drawn in a Screen, and
  714.            my_screen is a pointer to that screen, you write:
  715.            my_screen->RastPort.
  716.  
  717. image:     (struct Image *) Pointer to an Image structure which
  718.            has been initialized with your requirements.
  719.  
  720. x:         (long) Number of pixels added to the x position of
  721.            the image.
  722.  
  723. y:         (long) Number of lines added to the y position of
  724.            the image.
  725.  
  726.  
  727. A call to print an image using my_image structure would look
  728. something like this:
  729.  
  730.   DrawImage( my_window->RPort, &my_image, 0, 0 );
  731.  
  732.  
  733.  
  734. 3.6  FUNCTIONS
  735.  
  736. Here are the three functions you use when you want to draw
  737. lines/characters/images into a RastPort (Screen/Window):
  738.  
  739. DrawBorder()
  740.  
  741.   This function draws the specified Borders into a RastPort
  742.   (Screen/Window).
  743.  
  744.   Synopsis:  DrawBorder( rast_port, border, x, y );
  745.  
  746.   rast_port: (struct RastPort *) Pointer to a RastPort.
  747.  
  748.              If the lines should be drawn in a window, and
  749.              my_window is a pointer to that window, you write:
  750.              my_window->RPort.
  751.           
  752.              If the lines should be drawn in a Screen, and
  753.              my_screen is a pointer to that screen, you write:
  754.              my_screen->RastPort.
  755.  
  756.   border:    (struct Border *) Pointer to a Border structure
  757.              which has been initialized with your requirements.
  758.  
  759.   x:         (long) Number of pixels added to the x coordinates.
  760.  
  761.   y:         (long) Number of lines added to the y coordinates.
  762.  
  763.  
  764. PrintIText()
  765.  
  766.   This function prints text into a RastPort (Screen/Window).
  767.  
  768.   Synopsis:   PrintIText( rast_port, intui_text, x, y );
  769.  
  770.   rast_port:  (struct RastPort *) Pointer to a RastPort.
  771.  
  772.               If the text should be printed in a window, and
  773.               my_window is a pointer to that window, you write:
  774.               my_window->RPort.
  775.           
  776.               If the text should be printed in a Screen, and
  777.               my_screen is a pointer to that screen, you write:
  778.               my_screen->RastPort.
  779.  
  780.   intui_text: (struct IntuiText *) Pointer to a IntuiText
  781.               structure which has been initialized with your
  782.               requirements.
  783.  
  784.   x:          (long) Number of pixels added to the x position
  785.               of the characters.
  786.  
  787.   y:          (long) Number of lines added to the y position
  788.               of the characters.
  789.  
  790.  
  791. DrawImage()
  792.  
  793.   This function draws the specified images into a RastPort
  794.   (Screen/Window).
  795.  
  796.   Synopsis:  DrawImage( rast_port, image, x, y );
  797.  
  798.   rast_port: (struct RastPort *) Pointer to a RastPort.
  799.  
  800.              If the images should be drawn in a window, and
  801.              my_window is a pointer to that window, you write:
  802.              my_window->RPort.
  803.  
  804.              If the images should be drawn in a Screen, and
  805.              my_screen is a pointer to that screen, you write:
  806.              my_screen->RastPort.
  807.  
  808.   image:     (struct Image *) Pointer to an Image structure
  809.              which has been initialized with your requirements.
  810.  
  811.   x:         (long) Number of pixels added to the x position of
  812.              the image.
  813.  
  814.   y:         (long) Number of lines added to the y position of
  815.              the image.
  816.  
  817.  
  818.  
  819. 3.7  EXAMPLES
  820.  
  821. Here are some examples on how to draw lines (Border), print
  822. text (IntuiText) and draw pictures (Image):
  823.  
  824. Example1
  825.   This program will open a normal window which is connected to
  826.   the Workbench Screen. We will then draw a strange line with
  827.   help of Intuition's Border structure.
  828.  
  829. Example2
  830.   This program will open a normal window which is connected to
  831.   the Workbench Screen. We will then draw two rectangles with
  832.   different colours. This shows how you can link Border
  833.   structures to each other in order to get the desired effects.
  834.  
  835. Example3
  836.   This program will open a normal window which is connected to
  837.   the Workbench Screen. We will then print a text string with
  838.   help of Intuition's IntuiText structure.
  839.  
  840. Example4
  841.   Same as Example3 except that the text will be printed with
  842.   underlined italic characters.
  843.  
  844. Example5
  845.   This program will open a normal window which is connected to
  846.   the Workbench Screen. We will then draw the little nice arrow
  847.   we talked so much about.
  848.  
  849. Example6
  850.   Same as Example5 except that we will draw it several times in
  851.   different colours. This shows how PlanePick/PlaneOnOff works.
  852.  
  853. Example7
  854.   This program will open a normal window which is connected to
  855.   the Workbench Screen. We will then draw the nice 4 colour
  856.   face that was described in chapter 3.5 IMAGES.
  857.  
  858. Example8
  859.   This program will open a normal window which is connected to
  860.   a 16-colour Custom screen. In the window we will draw the
  861.   famous AMIGA-logo.